home *** CD-ROM | disk | FTP | other *** search
/ Linux Cubed Series 3: Developer Tools / Linux Cubed Series 3 - Developer Tools.iso / devel / lang / lisp / stk-3.0 / stk-3 / blt-for-STk-3.0 / blt-1.9 / man / htext.man < prev    next >
Encoding:
Text File  |  1995-07-01  |  14.2 KB  |  345 lines
  1. '\"
  2. '\" Copyright 1991-1994 by AT&T Bell Laboratories.
  3. '\"
  4. '\" Permission to use, copy, modify, and distribute this software
  5. '\" and its documentation for any purpose and without fee is hereby
  6. '\" granted, provided that the above copyright notice appear in all
  7. '\" copies and that both that the copyright notice and warranty
  8. '\" disclaimer appear in supporting documentation, and that the
  9. '\" names of AT&T Bell Laboratories any of their entities not be used
  10. '\" in advertising or publicity pertaining to distribution of the
  11. '\" software without specific, written prior permission.
  12. '\"
  13. '\" AT&T disclaims all warranties with regard to this software, including
  14. '\" all implied warranties of merchantability and fitness.  In no event
  15. '\" shall AT&T be liable for any special, indirect or consequential
  16. '\" damages or any damages whatsoever resulting from loss of use, data
  17. '\" or profits, whether in an action of contract, negligence or other
  18. '\" tortuous action, arising out of or in connection with the use or
  19. '\" performance of this software.
  20. '\"
  21. '\" Hypertext widget created by George Howlett.
  22. '\"
  23. .so man.macros
  24. .HS blt_htext cmds
  25. .BS
  26. '\" Note:  do not modify the .SH NAME line immediately below!
  27. .SH NAME
  28. blt_htext \- Create and manipulate hypertext widgets
  29. .SH SYNOPSIS
  30. \fBblt_htext\fP \fIpathName \fR[\fIoptions\fR]
  31. .SH "STANDARD OPTIONS"
  32. .LP
  33. .nf
  34. .ta 4c 8c 12c
  35. \fBbackground\fR    \fBcursor\fR    \fBfont\fR    \fBforeground\fR
  36. \fBtext\fR    \fBxScrollCommand\fR    \fByScrollCommand\fR
  37. .fi
  38. .LP
  39. See the ``options'' manual entry for details on the standard options.
  40. .ta 4c
  41. .SH "WIDGET-SPECIFIC OPTIONS"
  42. .LP
  43. .nf
  44. Name:    \fBfileName\fR
  45. Class:    \fBFileName\fR
  46. Command-Line Switch:    \fB\-filename\fR
  47. .fi
  48. .IP
  49. Specifies a \fBblt_htext\fP file to be displayed in the window. 
  50. If the value is the empty string, the \fB-text\fR option is used instead.
  51. See the section 
  52. .SB FILE FORMAT
  53. for a description of the \fBblt_htext\fP 
  54. file format.
  55. .LP
  56. .nf
  57. Name:    \fBheight\fR
  58. Class:    \fBHeight\fR
  59. Command-Line Switch:    \fB\-height\fR
  60. .fi
  61. .IP
  62. Specifies the desired height of the viewport window. The value must be in 
  63. a form accepted by \fBTk_GetPixels\fR. If the value is less than one, the window will
  64. grow to accommodate the entire length of text.
  65. .LP
  66. .nf
  67. Name:    \fBspecialChar\fR
  68. Class:    \fBSpecialChar\fR
  69. Command-Line Switch:    \fB\-specialchar\fR
  70. .fi
  71. .IP
  72. Specifies the ASCII value of the special double character delimiters.
  73. In \fBblt_htext\fP files, the text between these special characters is 
  74. evaluated as a block of Tcl commands. The default special character 
  75. is the \fIpercent sign\fR.
  76. .LP
  77. .nf
  78. Name:    \fBlineSpacing\fR
  79. Class:    \fBLineSpacing\fR
  80. Command-Line Switch:    \fB\-linespacing\fR
  81. .fi
  82. .IP
  83. Specifies the spacing between each line of text.  The value must
  84. be in a form accepted by \fBTk_GetPixels\fR. The default value is 1 pixel.
  85. .LP
  86. .nf
  87. Name:    \fBwidth\fR
  88. Class:    \fBWidth\fR
  89. Command-Line Switch:    \fB\-width\fR
  90. .fi
  91. .IP
  92. Specifies the desired width of the viewport window.  The value must be in a 
  93. form
  94. accepted by \fBTk_GetPixels\fR. If the value is less than one, the window will
  95. grow to accommodate the widest line of text.
  96. .LP
  97. .nf
  98. Name:    \fBxScrollUnits\fR
  99. Class:    \fBScrollUnits\fR
  100. Command-Line Switch:    \fB\-xscrollunits\fR
  101. .fi
  102. .IP
  103. Specifies the horizontal scrolling distance. The default is 10 pixels.
  104. .LP
  105. .nf
  106. Name:    \fByScrollUnits\fR
  107. Class:    \fBScrollUnits\fR
  108. Command-Line Switch:    \fB\-yscrollunits\fR
  109. .fi
  110. .IP
  111. Specifies the vertical scrolling distance. The default is 10 pixels.
  112. .BE
  113. .SH DESCRIPTION
  114. .PP
  115. The \fBblt_htext\fR command creates a new window (given by the 
  116. \fIpathName\fR argument) and makes it into a \fBblt_htext\fP widget.
  117. Additional options, described above, may be specified on the command line
  118. or in the option database to configure aspects of the widget such as its 
  119. color and font.  At the time this command is invoked, there must not 
  120. exist a window named \fIpathName\fR, but \fIpathName\fR's parent must exist.
  121. The \fBblt_htext\fR command returns its \fIpathName\fR.   
  122. .PP
  123. The \fBblt_htext\fP widget is hybrid of a non-editable text widget and
  124. a geometry manager (e.g. the packer).  It displays text (optionally read
  125. from file) in a window.  Text can be scrolled either horizontally or
  126. vertically using the \fBblt_htext\fR window as a viewport.
  127. In addition, Tcl commands can be embedded into 
  128. the text which are evaluated as the text is parsed.  Text between special
  129. double characters (percent signs "%%") is immediately passed to the Tcl 
  130. interpreter for evaluation.  
  131. .PP
  132. Furthermore, any widget or widget hierarchy can be packed in-line and made 
  133. to appear on the current line of the text.  Widgets are packed using the 
  134. \fBblt_htext append\fP command.  All widgets must be children of the 
  135. \fBblt_htext\fP window and must already exist before packing. 
  136. Once a widget has been packed it cannot be moved to a different
  137. position within the text.  Widgets can be resized but they will remain 
  138. at the same position within the text.
  139. .PP
  140. Before a file or text string is parsed by the \fBblt_htext\fR widget,
  141. all the widget's current children are destroyed.  You can reload files or text 
  142. without worrying about unmapping or destroying each child window beforehand.
  143. .PP
  144. Setting the either the \fB-filename\fR or \fB-text\fR configuration option 
  145. will adjust the value of the other.  If both options are set, the file 
  146. takes precedence.  When a new file is read using the \fB-filename\fR option,
  147. the value of the \fB-text\fR option is reset to the empty string.  Likewise, 
  148. when the \fB-text\fR option is set, the string representing the 
  149. \fB-filename\fR option is cleared.
  150. .SH FILE FORMAT
  151. The format of \fBblt_htext\fP text file is typically ASCII text.  
  152. Text enclosed by special double characters (by default, percent signs '%%') 
  153. is interpreted and executed as Tcl commands.  
  154. The special character  may be specified by the \fB-specialchar\fP option. 
  155. In the following example of a \fBblt_htext\fP file,  a button widget 
  156. is appended to the text between  the words "\fCa\fP" and "\fCwhich\fP".  
  157. The \fIpathName\fR of the \fBblt_htext\fP widget is "\fC.ht\fP".
  158. .DS L
  159. \fCThis will be displayed as normal text. 
  160. But this will become a %% 
  161.   button .ht.button -text "button" -fg red
  162.   .ht append .ht.button 
  163. %% which can invoke a Tcl command.\fR
  164. .DE
  165. .LP
  166. .SH "VARIABLES"
  167. .PP
  168. The following global Tcl variables are maintained when an 
  169. \fBblt_htext\fR file is parsed.  
  170. .TP
  171. \fBblt_htext(widget)\fR 
  172. is the pathname of the \fBblt_htext\fP widget.
  173. .TP
  174. \fBblt_htext(file)\fR 
  175. is the name of the file the \fBblt_htext\fP widget is currently parsing.  
  176. It is the empty string when the \fB\-text\fP option is used.
  177. .TP
  178. \fBblt_htext(line)\fR 
  179. is the current line number in the text.  
  180. .PP
  181. This information might be used to construct hyper links 
  182. between different files and/or lines.
  183. .LP
  184. .SH "WIDGET COMMAND"
  185. .PP
  186. The \fBblt_htext\fP command creates a new Tcl command whose
  187. name is \fIpathName\fR.  This command may be used to invoke various
  188. operations on the widget.  It has the following general form:
  189. .DS C
  190. \fIpathName option \fR?\fIargs\fR?
  191. .DE
  192. \fIOption\fR and \fIargs\fR determine the exact behavior of the command.
  193. .PP
  194. The following widget commands are available for \fBblt_htext\fP widgets:
  195. .TP
  196. \fIpathName \fBappend \fIchild\fR
  197. Packs \fIchild\fP at the current position in the text. \fIChild\fP is 
  198. the name of a window to be packed into the \fBblt_htext\fP window. 
  199. \fIChild\fR must be a child of the \fBblt_htext\fP window and 
  200. may be specified by either its \fIpathName\fP or \fIname\fP.
  201. .TP
  202. \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR?
  203. Queries or modifies the configuration options of the widget.  If no
  204. \fIoption\fR is specified, returns a list describing all of the
  205. available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for
  206. information on the format of this list).  If \fIoption\fR is specified
  207. with no \fIvalue\fR, then the command returns a list describing the
  208. one named option (this list will be identical to the corresponding
  209. sublist of the value returned if no \fIoption\fR is specified).  If
  210. one or more \fIoption\-value\fR pairs are specified, then the command
  211. modifies the given widget option(s) to have the given value(s); in
  212. this case the command returns the empty string.  \fIOption\fR may have
  213. any of the values accepted by the \fBblt_htext\fR command.
  214. .TP
  215. \fIpathName \fBgotoline \fR?\fIline\fR?
  216. Scrolls the text to \fIline\fP.  \fILine\fP is the line number of the
  217. new text position and is bounded by the range of lines in the text.
  218. If a \fIline\fP argument is not present, the current line number is returned.
  219. .TP
  220. \fIpathName \fBchildconfigure \fIchild\fR
  221. Queries or resets the positioning of \fIchild\fR or the size of the 
  222. cavity surrounding it. This command is similar to the \fBconfigure\fR 
  223. command, except that it applies to the options of the child window and its
  224. cavity, whereas \fBconfigure\fR applies  to the options for the widget as 
  225. a whole. \fIChild\fP is the name of window packed into the \fBblt_htext\fR 
  226. window (by the \fBblt_htext append\fR command). The child widget may be
  227. specified by either its \fIpathName\fP or \fIname\fP.
  228. The following options are available.
  229. .RS
  230. .TP
  231. \fB\-anchor \fIanchorPos\fR
  232. Specifies how the child window will be arranged if there is extra space 
  233. in the cavity surrounding the window. \fIAnchorpos\fR may have any of the 
  234. forms accepted by \fBTk_GetAnchor\fR.  For example, if \fIanchorPos\fR is 
  235. \fBcenter\fR then the window is centered in the cavity; 
  236. if \fIanchorPos\fR is \fBw\fR then the window will be drawn such it touches
  237. the leftmost edge of the cavity. This option defaults to \fBcenter\fR.
  238. .TP
  239. \fB\-fill \fIstyle\fR
  240. Indicates if the child window should be expanded to occupy any extra space 
  241. in the cavity surrounding it.  \fIStyle\fR must be one of the following:
  242. \fBnone\fR, \fBx\fR, \fBy\fR, \fBboth\fR.  If \fIstyle\fR is \fBx\fR,
  243. the width of the child window is expanded to fill the cavity.  
  244. If \fIstyle\fR is \fBy\fR, the height is expanded. The default is \fBnone\fR.
  245. .TP
  246. \fB\-height \fIvalue\fR
  247. Species the height of the cavity containing the child window.  
  248. \fIValue\fP must be in a form accepted by \fBTk_GetPixels\fR.
  249. If \fIvalue\fP is greater than zero, the cavity is resized to that height.  
  250. If the requested window height is greater than the cavity's height, the
  251. window will be reduced to fit the cavity.
  252. By default, the cavity is requested height of the child window. 
  253. .TP
  254. \fB\-ipadx \fIvalue\fR
  255. Specifies extra padding to the left and right sides of the child window. 
  256. \fIValue\fR must be in a form accepted by \fBTk_GetPixels\fR.
  257. .TP
  258. \fB\-ipady \fIvalue\fR
  259. Specifies extra padding to the top and bottom sides of the child window.
  260. \fIValue\fR must be in a form accepted by \fBTk_GetPixels\fR.
  261. .TP
  262. \fB\-justify \fIvalue\fR
  263. Justifies the vertical position of the cavity containing the child widget 
  264. in relation to the line of text. \fIValue\fR must be either \fBtop\fP, 
  265. \fBbottom\fR, or  \fBcenter\fR. By default, the child widget is centered 
  266. along the baseline of the line of text.
  267. .TP
  268. \fB\-padx \fIvalue\fR
  269. Specifies the padding to the left and right sides of the cavity containing
  270. the child window. 
  271. \fIValue\fR must be in a form accepted by \fBTk_GetPixels\fR.
  272. .TP
  273. \fB\-pady \fIvalue\fR
  274. Specifies the padding on the top and bottom sides of the cavity containing 
  275. the child window.
  276. \fIValue\fR must be in a form accepted by \fBTk_GetPixels\fR.
  277. .TP
  278. \fB\-relheight \fIvalue\fR
  279. Specifies the height of the cavity containing the child window relative to 
  280. the height of the viewport window.  \fIValue\fP is real number indicating
  281. the ratio of the height of the cavity to the viewport.  If \fIvalue\fR 
  282. is 0.0 or less, the request is ignored and the height of the 
  283. cavity is the requested height of the child window. 
  284. .TP
  285. \fB\-relwidth \fIvalue\fR
  286. Specifies the width of the cavity containing the child window relative to 
  287. the width of the viewport window.  \fIValue\fP is real number indicating
  288. the ratio of the width of the cavity to the viewport.  If \fIvalue\fR 
  289. is 0.0 or less, the request is ignored and the width of the cavity is 
  290. the requested width of the child window. 
  291. .TP
  292. \fB\-width \fIvalue\fR
  293. Species the width of the cavity containing the child window.  
  294. \fIValue\fP must be in a form accepted by \fBTk_GetPixels\fR.
  295. If \fIvalue\fP is greater than zero, the cavity is resized to that width.  
  296. If the requested window width is greater than the cavity's width, the
  297. window will be reduced to fit the cavity.
  298. By default, the cavity is requested width of the child window. 
  299. .RE
  300. .TP
  301. \fIpathName \fBscan\fR \fIoption args\fR
  302. This command is used to implement scanning on texts.  It has
  303. two forms, depending on \fIoption\fR:
  304. .RS
  305. .TP
  306. \fIpathName \fBscan mark \fIy\fR
  307. Records \fIy\fR and the current view in the text window;  used in
  308. conjunction with later \fBscan dragto\fR commands.  Typically this
  309. command is associated with a mouse button press in the widget.  It
  310. returns an empty string.
  311. .TP
  312. \fIpathName \fBscan dragto \fIy\fR
  313. This command computes the difference between its \fIy\fR argument
  314. and the \fIy\fR argument to the last \fBscan mark\fR command for
  315. the widget.  It then adjusts the view up or down by 10 times the
  316. difference in y-coordinates.  This command is typically associated
  317. with mouse motion events in the widget, to produce the effect of
  318. dragging the text at high speed through the window.  The return
  319. value is an empty string.
  320. .RE
  321. .TP
  322. \fIpathName \fBsearch \fIpattern\fR ?\fIfrom\fR? ?\fIto\fR?
  323. Returns the number of the next line matching \fIpattern\fR.  \fIPattern\fR is
  324. a string which obeys the matching rules of \fBTcl_StringMatch\fR. 
  325. \fIFrom\fR and \fIto\fR are text line numbers (inclusive) which 
  326. bound the search.  
  327. If no match for \fIpattern\fR can be found, \fB-1\fR is returned.
  328. .TP
  329. \fIpathName \fBxview \fR?\fIposition\fR?
  330. Moves the viewport horizontally to the new text x-coordinate position.  
  331. \fIPosition\fR is the offset from the left side of the text to the current 
  332. position and must be in a form accepted by \fBTk_GetPixels\fR. If \fIposition\fR
  333. is not present, the current text position is returned.
  334. .TP
  335. \fIpathName \fByview \fR?\fIposition\fR?
  336. Moves the viewport vertically to the new text y-coordinate position.  
  337. \fIPosition\fR is the offset from the top of the text to the current 
  338. position and must be in a form accepted by \fBTk_GetPixels\fR. If \fIposition\fR
  339. is not present, the current text position is returned.
  340. .SH BUGS
  341. Text with embedded tabs can be obscured by child windows when scrolled 
  342. horizontally.
  343. .SH KEYWORDS
  344. hypertext, widget
  345.